<HTML><HEAD><TITLE>write_term(+Stream, ?Term, ++Options)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Term I/O</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>write_term(+Stream, ?Term, ++Options)</H1>
The term Term is written to the output stream Stream in a format specified by Options
<DL>
<DT><EM>Stream</EM></DT>
<DD>Integer (stream number) or Atom (reserved or user-defined symbolic stream name)
</DD>
<DT><EM>Term</EM></DT>
<DD>An arbitrary term
</DD>
<DT><EM>Options</EM></DT>
<DD>List of option terms
</DD>
</DL>
<H2>Description</H2>
<P>
    This is a generalisation of the predicates write/2, writeq/2, print/2,
    display/2, write_canonical/2. It is used to write an arbitrary term
    Term onto the current output stream according to the given options.
    Options is a (possibly empty) list of the following options:
</P>
<DL>
    <DT><STRONG>as(term)</STRONG> -- default</DT><DD><P>
	do not assume any particular meaning of the printed term.
	</P></DD>

    <DT><STRONG>as(clause)</STRONG></DT><DD><P>
	print the term as a clause, i.e. clause macros will be taken into
	account.
	</P></DD>

    <DT><STRONG>as(goal)</STRONG></DT><DD><P>
	print the term as a goal, i.e. goal write transformations will
	be taken into account.
	</P></DD>

    <DT><STRONG>attributes(none)</STRONG> -- default</DT><DD><P>
	do not print any variable attributes, i.e. print attributed
	variables like plain variables.
	</P></DD>

    <DT><STRONG>attributes(pretty)</STRONG></DT><DD><P>
	variable attributes are printed using the corresponding print
	handlers. See meta_attribute/2.
	</P></DD>

    <DT><STRONG>attributes(full)</STRONG></DT><DD><P>
	print the full contents of all variable attributes.  This is
	necessary if the term is to be written out and read back in.
	</P></DD>

    <DT><STRONG>compact(false)</STRONG> -- default</DT><DD><P>
	print extra blank space (around operators, after commas, etc.)
	for better readability.
	</P></DD>

    <DT><STRONG>compact(true)</STRONG></DT><DD><P>
	don't print blank space unless necessary.
	</P></DD>

    <DT><STRONG>depth(0)</STRONG> -- default</DT><DD><P>
	print the term only up to a maximum nesting depth determined
	by the (stream-specific or global) flag 'print_depth'. See
	get_stream_info/3 and get_flag/2.
	</P></DD>

    <DT><STRONG>depth(MaxDepth)</STRONG></DT><DD><P>
	print the term only up to a maximum nesting depth of MaxDepth.
	MaxDepth is a positive integer.
	</P></DD>

    <DT><STRONG>depth(full)</STRONG></DT><DD><P>
	do not observe any depth limit and print the whole term. Note that
	this will cause looping when the term is cyclic.
	</P></DD>

    <DT><STRONG>dotlists(false)</STRONG> -- default</DT><DD><P>
	write lists in the common square bracket notation, e.g. [1, 2].
	</P></DD>

    <DT><STRONG>dotlists(true)</STRONG></DT><DD><P>
	write lists in the dot functor notation rather than using the
	square bracket notation, e.g. .(1, .(2, [])) rather than [1, 2].
	</P></DD>

    <DT><STRONG>newlines(false)</STRONG> -- default</DT><DD><P>
	print newline (NL) characters as escape sequence, when they
	occur in quoted atoms or strings.
	</P></DD>

    <DT><STRONG>newlines(true)</STRONG></DT><DD><P>
	print newline (NL) characters as newlines rather than as an
	escape sequence, even when they occur in quoted atoms or strings.
	This only makes sense together with the quoted(true) option.
	</P></DD>

    <DT><STRONG>numbervars(false)</STRONG> -- default</DT><DD><P>
	do not treat '$VAR'/1 terms specially.
	ISO-Prolog compatible.
	</P></DD>

    <DT><STRONG>numbervars(true)</STRONG></DT><DD><P>
	any term of the form '$VAR'(N), where N is a non-negative integer,
	is printed as a variable name consisting of a capital letter
	followed by a number. The capital letter is the ((N mod 26)+1)st
	letter of the alphabet, and the integer is N//26.
	If N is an atom, this atom gets printed instead of the term.
	ISO-Prolog compatible.
	</P></DD>

    <DT><STRONG>operators(true)</STRONG> -- default</DT><DD><P>
	obey operator declarations. All infix, prefix and postfix operators
	are printed in infix, prefix or postfix form, respectively.
	</P></DD>

    <DT><STRONG>operators(false)</STRONG></DT></DT><DD><P><P>
	ignore operator declarations.  All terms are written in the canonical
	notation, with a functor followed by the arguments in parentheses.
	</P></DD>

    <DT><STRONG>portrayed(false)</STRONG> -- default</DT><DD><P>
	do not use portray/1,2.
	</P></DD>

    <DT><STRONG>portrayed(true)</STRONG></DT><DD><P>
	call the user-defined predicate portray/1,2 in the way print/1,2
	does.
	</P></DD>

    <DT><STRONG>quoted(false)</STRONG> -- default</DT><DD><P>
	do not print quotes around strings or atoms.
	ISO-Prolog compatible.
	</P></DD>

    <DT><STRONG>quoted(true)</STRONG></DT><DD><P>
	quote atoms and strings if necessary.
	ISO-Prolog compatible.
	</P></DD>

    <DT><STRONG>transform(true)</STRONG> -- default</DT><DD><P>
	apply portray (write) transformations before printing.
	</P></DD>

    <DT><STRONG>transform(false)</STRONG></DT><DD><P>
	do not apply any portray (write) transformations.
	</P></DD>

    <DT><STRONG>variables(default)</STRONG> -- default</DT><DD><P>
	print variables using their source name, if available.
	Otherwise print a system-generated name, which consists of
	an underscore and a number, e.g. <CODE>_123</CODE>.
	Note that this format cannot be reliably read back, because
	different variables may have the same source name.
	</P></DD>

    <DT><STRONG>variables(raw)</STRONG></DT><DD><P>
	print all variables using a system-generated name, which
	consists of an underscore and a number, e.g. <CODE>_123</CODE>.
	This format is suitable when the term needs to be read back
	later.  It makes sure that multiple occurrences of the same
	variable have the same name, and different variables have
	different names.
	</P></DD>

    <DT><STRONG>variables(full)</STRONG></DT><DD><P>
	print variables using their source name, if available, followed
	by a unique number, e.g. Alpha_132. Variables without source
	name are printed in the raw format. Since variables with
	identical source names are named apart, this format is suitable
	when the term needs to be read back later.
	</P></DD>

    <DT><STRONG>variables(anonymous)</STRONG></DT><DD><P>
	print every variable as a simple underscore. Any information about
	multiple occurrences of a variable is lost with this format. It is
	mainly useful to produce output that can be compared easily with
	the output of a different Eclipse session.
	</P></DD>

</DL>
<P>
    When an option is omitted altogether, then the corresponding option
    settings for the output stream will come into effect (see
    set_stream_property/3, get_stream_info/3, open/4).
</P>
    The following additional options are supported for compatibility
    with other Prolog systems:
<DL>
    <DT><STRONG>ignore_ops(true)</STRONG></DT><DD><P>
    	the same as [operators(false),dotlists(true),transform(false)].
	ISO-Prolog compatibility.
	</P></DD>

    <DT><STRONG>ignore_ops(false)</STRONG></DT><DD><P>
    	the same as [operators(true),dotlists(false),transform(true)].
	ISO-Prolog compatibility.
	</P></DD>

    <DT><STRONG>max_depth(0)</STRONG></DT><DD><P>
    	the same as depth(full).
	SICStus-Prolog compatibility.
	</P></DD>

    <DT><STRONG>max_depth(N)</STRONG></DT><DD><P>
    	the same as depth(N).
	SICStus-Prolog compatibility.
	</P></DD>
</DL>
    The correspondence between write_term/2,3 and the other output predicates
    is as follows:
<DL>
    <DT>write(T)</DT><DD><P>
	write_term(T, [])
	</P></DD>

    <DT>writeq(T)</DT><DD><P>
	write_term(T, [variables(raw),attributes(full),transform(false),
	quoted(true),depth(full)])
	</P></DD>

    <DT>write_canonical(T)</DT><DD><P>
	write_term(T, [variables(raw),attributes(full),transform(false),
	quoted(true),depth(full),dotlist(true),operators(false)])
	</P></DD>

    <DT>print(T)</DT><DD><P>
	write_term(T, [portrayed(true)])
	</P></DD>

    <DT>display(T)</DT><DD><P>
	write_term(T, [dotlist(true),operators(false)])
	</P></DD>
</DL>
<P>
   Note that as usual, the output is buffered, so it may need to be flushed
   either by closing the stream, by writing again or by using flush/1.
</P>

<H3>Modes and Determinism</H3><UL>
<LI>write_term(+, ?, ++) is det
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Stream is not instantiated.
<DT><EM>(5) type error </EM>
<DD>Stream is not an atom or an integer.
<DT><EM>(5) type error </EM>
<DD>Options is not a list of compound terms.
<DT><EM>(6) out of range </EM>
<DD>Options list contains a unrecognised option.
<DT><EM>(192) illegal stream mode </EM>
<DD>Stream is not an output stream.
<DT><EM>(193) illegal stream specification </EM>
<DD>Stream is an illegal stream specification.
</DL>
<H2>Examples</H2>
<PRE>
	?- write_term(*(^(1,2),+(3,4)), []).
	1 ^ 2 * (3 + 4)

	?- write_term(*(^(1,2),+(3,4)), [operators(false)]).
	*(^(1, 2), +(3, 4))

	?- write_term(['a-b',"cd"], []). 
	[a-b, cd]

	?- write_term(['a-b',"cd"], [quoted(true)]).
	['a-b', "cd"]

	?- write_term(['a-b',"cd"], [quoted(true),dotlists(true)]).
	.('a-b', .("cd", []))

</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/ioterm/write_term-2.html">write_term / 2</A>, <A HREF="../../kernel/ioterm/display-2.html">display / 2</A>, <A HREF="../../kernel/ioterm/print-2.html">print / 2</A>, <A HREF="../../kernel/ioterm/printf-3.html">printf / 3</A>, <A HREF="../../kernel/ioterm/write-2.html">write / 2</A>, <A HREF="../../kernel/ioterm/writeq-2.html">writeq / 2</A>, <A HREF="../../kernel/ioterm/write_canonical-2.html">write_canonical / 2</A>, <A HREF="../../kernel/iostream/get_stream_info-3.html">get_stream_info / 3</A>, <A HREF="../../kernel/env/get_flag-2.html">get_flag / 2</A>
</BODY></HTML>
